Using triggers

Use triggers and actions to create interactions based on user input. A trigger defines a condition and an action defines what the trigger does when that condition is met. For example, to execute a JavaScript script when a node is attached to the scene graph, add the On Attached trigger to that node and add the Execute Script action to that trigger.

Kanzi Studio has a range of actions which you can add to a trigger. For example, you can add an action to print to the Log window (Write Log), set a property to a certain value (Set Property), navigate to a Page node (Navigate to Page), or change application theme (Activate Theme).

Trigger messages

When a trigger intercepts a message that originates from an action you can set what the trigger does with the message. You can:

• Intercept the message, act on it, and let it continue traveling up or down the project tree.
• Intercept the message, act on it, and handle it. When a trigger handles a message it consumes it so that the message stops at the trigger that handles it and no other node can intercept it.

With a trigger you can intercept a message either at the node where the message originates, or in a trigger in any of its ancestor or descendant nodes. You can intercept many different message types in the same node. When a message travels up the project tree, the message bubbles. When a message travels down the project tree, the message tunnels. You can set in the action that creates the message whether the message bubbles, tunnels, or both bubbles and tunnels.

For example, if the action creates a bubbling message, after an action generates a message, the message bubbles from the node that receives the input to its parent node, then to the parent's parent, and so on until a trigger intercepts the message. If the trigger also handles the message, the message stops bubbling (traveling up the project tree). If none of the ancestors handle the message, the message travels all the way to the root node of the project.

By default all triggers handle their own messages. You can control the handling of trigger messages by setting the Set Message Handled property in the Trigger Settings.

Getting started

To get started with triggers, see:

• Adding a trigger
• Setting the handling of trigger messages
• Adding conditions to a trigger
  • Creating a condition using a value from a property
  • Creating a condition using a value from a message
• Removing a trigger

For a list of all the triggers you can use in Kanzi Studio, see Triggers reference.

For a list of all the actions you can add to a trigger in Kanzi Studio, see Actions reference.

Adding a trigger

The most common place to add a triggers is in the node that uses the trigger, but you can add a trigger to any node.

To add a trigger:

1. In the Project create or select a node to which you want to add a trigger.
   For example, create a Button 2D node. When you create the Button 2D node it already has a Button: Click trigger.
   
2. In the Node Components > Triggers section right-click, select Add Trigger, and select a trigger that intercepts the type of message you want to intercept.
   For example, add an On Attached trigger. The On Attached trigger is set off when Kanzi attaches the node to the scene graph.
   
3. In the Node Components > Triggers section click the Add dropdown menu for the trigger you added in the previous step and select an action.
   For example, select the Write Log action and enter a message you want to write to the Log window when the trigger is set off. The Write Log action is useful when you want to verify that the node received the input.
   You can add any number of actions. Kanzi carries out the actions in the order beginning from the first action.
   
   When Kanzi attaches the node, it prints the message you entered as the value of the Log Message property to the Log window. To open the Log window, in the main menu select Window > Log.
   
4. (Optional) If you want the trigger to be set off only under specific conditions, in the Node Components > Triggers section under the trigger for which you want to set a condition, click Trigger Settings, in the Trigger Settings Editor click Add condition, and define the condition. See Adding conditions to a trigger.
   

Setting the handling of trigger messages

When a trigger handles a message it consumes it so that the message stops at the trigger that handles it and no other node can intercept it. See Creating custom messages in Kanzi Studio.

To set the handling of trigger messages:

1. In the Node Components > Triggers section under the trigger for which you want to set message handling, click Trigger Settings.
   
2. In the Trigger Settings Editor set:
   • Set Message Handled property:
   • When you enable the Set Message Handled property, this trigger intercepts and handles the message. The message stops here, and does not continue neither bubbling nor tunneling in the project tree.
   • When you disable the Set Message Handled property, this trigger intercepts the message, but the message continues bubbling or tunneling in the project tree.
   • Routing Mode property:
     • Bubbling to intercept only bubbling messages.
     • Direct to intercept only messages that are sent directly to this node.
     • Tunneling to intercept only tunneling messages.
     • Tunneling and bubbling to intercept tunneling and bubbling messages.
   • Message Source property:
     • To intercept messages from a specific target item, do one of the following:
       • Select the item from the dropdown menu.
       • Select <Relative> and set the path to the item:
         
         • Separate node names with / to build the path.
         • Use . to access the current item.
         • Use .. to access the parent item of the current item.
         • Use # to access a node using an alias in the resource dictionary of the current node. See Using aliases.
     • To intercept messages from all sources, select <No Item>.
   

Adding conditions to a trigger

Trigger conditions enable you to set which conditions must be met for the trigger to set off. For example, you can define conditions to set off a trigger when the user navigates to a specific Page node, enable the user to click a button only when that button is visible, or enable the user to scroll a scroll view only when a specific Page node is active.

You can add conditions to triggers in the Trigger Condition Editor. You create a condition by comparing a value you define in the Value A section to the value you define in the Value B section using an operator you set with the Operator property.

You can create conditions to set off a trigger when:

• A value that comes from a property type matches a certain rule. See Creating a condition using a value from a property.
• A value that comes from a message matches a certain rule. See Creating a condition using a value from a message.

Creating a condition using a value from a property

You can define a trigger condition to set off a trigger when a property you select gets a value you set in that condition. For example, you can create a condition which allows the user to scroll a Scroll View node only when a specific Page node is active.

To create a condition using a value from a property:

1. In the Project select or create a node with a trigger to which you want to add a condition and in the Node Components for the trigger click Trigger Settings. See Adding a trigger.
   The Trigger Settings Editor opens.
   For example, create a Scroll View 2D node with a Scrolled trigger and in the Node Components click Trigger Settings for that trigger. See Using the Scroll View nodes.
   
2. In the Trigger Settings Editor click Add condition.
   The Trigger Condition Editor opens.
   
3. In the Trigger Condition Editor set the condition that must be met for the trigger to set off. You create a condition by comparing a value you define in the Value A section to the value you define in the Value B section using an operator you set with the Operator property.
   In the Trigger Condition Editor set:
   • In the Value A section define the property type and value that you want to use for the condition. To use a value from a property, set:
     • Value From to Property
       
     • Item to the node the property of which you want to use for the condition
       For example, set it to a Page node.
     • Property to the property type that you want to use for the condition
       For example, set it to the Activation State property of the Page node you selected in the Item property.
       Use the Activation State property to find out whether a Page or Page Host node is active.

     

   • Operator to the operator you want to use to compare the value you defined in the Value A section to the value you define in the Value B section.
     For example, set it to = to create a condition where the trigger sets off only when the value you defined in the Value A section is equal to the value you define in the Value B section.
     
     
   • In the Value B section define the value to which you want to compare the value you defined in the Value A section. The Value From property defines where the value for the Value B comes from. Set the Value From property to:
     • Property to compare to a value from any property from any node in the project
     • Message to use a value from a message from a trigger in the node that you set in the Value A section in the Item property
     • Fixed when you want to use the same property from the node that you set in the Value A section and set a value for that property
     For example, set the Value From property to Fixed and then set the Fixed Value property to enabled.
     The data type of the Fixed Value property depends on the property type you set in the Value A section. In this example this is a Boolean property type Activation State of a Page node.
     
   Click Save.
   Here you created a condition which sets off a trigger when the user navigates to the Page node Media.
   

Creating a condition using a value from a message

You can define a trigger condition to set off a trigger when a message you select gets a value you set in that condition. You can use values from messages of these triggers:

• Scroll View
• List Box
• State Manager
• Keyboard

For example, you can set off a trigger when the user selects a specific item in a List Box node.

To create a condition using a value from a message:

1. In the Project select or create a node with a trigger to which you want to add a condition and in the Node Components for the trigger click Trigger Settings. See Adding a trigger.
   The Trigger Settings Editor opens.
   For example, create a Grid List Box 2D node with a List Box: Item Selected trigger and in the Node Components click Trigger Settings for that trigger. See Using the Grid List Box nodes.
   
   
2. In the Trigger Settings Editor click Add condition.
   The Trigger Condition Editor opens.
   
   
3. In the Trigger Condition Editor set the condition that must be met for the trigger to set off. You create a condition by comparing a value you define in the Value A section to the value you define in the Value B section using an operator you set with the Operator property.
   In the Trigger Condition Editor set:
   • In the Value A section set the message that you want to use for the condition. To use a value from a message, set:
     • Value From to Message
     • Argument to the message that you want to use for the condition
       For example, if you created a List Box: Item Selected trigger, set the Argument to Selection.
     
   • Operator to the operator you want to use to compare the value you defined in the Value A section to the value you define in the Value B section.
     For example, set it to = to create a condition where the trigger sets off only when the value you defined in the Value A section is equal to the value you define in the Value B section.
     
     
   • In the Value B section define the value to which you want to compare the value you defined in the Value A section. The Value From property defines where the value for the Value B comes from. Set the Value From property to:
     • Property to compare to a value from any property from any node in the project
     • Message to use a value from a message from a trigger in the node that you set in the Value A section in the Item property
     • Fixed when you want to use the same message that you set in the Value A section and set a value for that message
     For example, set the Value From property to Fixed and then set the Fixed Value property to 0.
     The data type of the Fixed Value property depends on the message type you set in the Value A section. In this example this is an integer.
     
   Click Save.
   In this example you created a condition which sets off a trigger when the user selects the first item in the Grid List Box 2D node.
   

Removing a trigger

To remove a trigger, in the Node Components > Triggers section right-click the trigger you want to remove and select Remove.

Using triggers in the API

For details, see the Trigger class in the API reference.

See also

Triggers

Handling user input

Using input manipulators

Using messages

Triggers reference

Actions reference

Keyboard input codes reference

Using scripts

Open topic with navigation